ASK · Design System · v1.0
last published · 2026-05-21
Volume 02 · Components, environments & compliance patterns

Power under control.

Every component, environment, and compliance pattern needed to build ASK at production fidelity. The system enforces structural safety through visual contracts — citation, validation, guardrail, and RBAC behaviour is not optional polish but a load-bearing part of the design.

42
Components
3
Environments
4
Mandatory patterns
120
Design tokens
▸

Voice & tone

ASK speaks like a highly capable, completely dependable corporate co-pilot. Technical authority grounded in industrial responsibility — never conversational vagueness, never hype.
Attribute
UX implication
Copy example
Authoritative
& pragmatic
Demystify AI mechanisms. Focus on verifiable accuracy and operational excellence. Strip out enthusiasm, marketing language, anthropomorphism.
"Grounded in certified corporate knowledge. Zero speculation."
Protective
yet enabling
Frame constraints as empowering infrastructure. The walls of the garden are what make it safe to plant.
"Your session is isolated within the private tenant. Data cannot leak to external models."
Deterministic
& accountable
Reject conversational vagueness. Rely strictly on evidence and auditable logic chains. Every assertion must be traceable.
"Review the cited source document before approving this workflow."
"
Core essence
Power under control. ASK shifts compliance from a restrictive bureaucratic barrier into an enabling platform for growth.
00

Tokens recap

A compact reference. The brand sheet has the full story, examples, and rules of use.
Ask Red
#E42438
Ink
#0A0A0A
Graphite
#2A2A2D
Steel
#6E6E76
Mist
#E8E8EA
Paper
#F7F6F4
Success
#1F8A5B
Warning
#B7791F
Danger
#C81B2E
Info
#2A6FDB
White
#FFFFFF
Rule
#D8D6D2
01

Primitives

Form controls and triggers. The atomic vocabulary. Every other component is built from these.
Button
button/*
Primary action triggers. One primary per surface. Use Secondary (Ink) for confirming flows, Outline for less-critical actions, Ghost in toolbars and tables.
VARIANTS
SIZES
WITH ICON
STATES
default
hover
focused
loading
disabled
Property model · variant, size, state, loading, icon-leading, icon-trailing Figma: button/{variant}/{state} · Code: @/components/ui/button
Input
input/text
Single-line text. Always paired with a Label and optional Help / Error text via the Field composite.
default
filled
focused
error
disabled
Composes with · Label, HelpText, ErrorText Figma: input/text/{state} · Code: @/components/ui/input
Selection controls
checkbox · radio · switch
Checkbox for many-of-many, Radio for one-of-many, Switch for an immediate on/off setting that takes effect without a save action.
CHECKBOX
Off On Indeterminate
RADIO
Auto-approve Manual review Read-only
SWITCH
Notifications Telemetry Beta features
Property · checked, disabled, indeterminate (checkbox only) Figma: checkbox/{state} · radio/{state} · switch/{state}
Textarea & Slider
input/textarea · input/slider
Multi-line text and continuous numeric input. Textarea resizes vertically only; Slider uses ASK Red on the active track.
Temperature0.7
Max steps12
Property · textarea: rows, maxLength · slider: min, max, step, value Figma: input/textarea · input/slider
Badge
badge/*
Status labels and counts. Always pair with a parent element — never on their own.
Draft Live Throttled Failed Queued v 2.3.1 128 +12.4%
Property · tone ∈ {neutral, success, warning, danger, info, outline} · dot (boolean) Figma: badge/{tone}
02

Feedback

Affirmation, errors, system status. The system's voice when it needs to speak.
Alert
alert/*
In-flow status. Persistent until dismissed or until the condition resolves. Not for transient feedback — use Toast for that.
Agent deployed
acme-onboarding-v3 is live in production. 12 instances running.
View run
Tool budget at 78%
This agent has used 234 of 300 web_search calls this billing period.
Connection to data source failed
postgres://prod-replica returned 5 consecutive timeouts. Auto-retry in 30s.
New model available
claude-opus-5 is now available in your region. Upgrade recommended.
Property · tone, title, body, action (optional) Figma: alert/{tone}
Toast, Tooltip, Progress
toast · tooltip · progress
Transient and ambient feedback.
TOAST · auto-dismisses 4s
Run completed in 1m 14s
API key copied to clipboard
TOOLTIP
Tool budget · 234 / 300
PROGRESS
determinate · 60%
success
indeterminate
z-index · tooltip 1000 · toast 1200 (above modal) Figma: toast/* · tooltip/* · progress/*
Skeleton & Empty state
skeleton · empty
Loading and zero states. Skeletons match the shape of incoming content; empty states give users a next action.
LOADING · SKELETON
No agents yet
Spin up your first agent to start automating workflows. Choose from a template or start from scratch.
Skeleton · width/height props. Empty · icon, title, description, action Figma: skeleton/{shape} · empty/{kind}
03

Overlays

UI that floats above the page. All overlays trap focus, close on Escape, and respect the system z-index scale.
Dialog
dialog/*
Centered modal for confirmation, focused tasks, or destructive actions. Backdrop dims at 60%.
Delete agent · acme-onboarding
This will stop the agent immediately and remove its history. Connected webhooks will be disabled.
Any in-flight runs will be marked as terminated. This action cannot be undone.
Property · title, description, destructive (boolean) · z 1100 Figma: dialog/{kind}
Sheet, Popover, Command palette
sheet · popover · command
Side panel, anchored menu, and global search.
Agent settings
Display name
Description
Auto-approve safe tool calls
Run actions
Re-run⌘R
Duplicate⌘D
Export
Delete⌘⌫
ESC
Agents
Create new agent⌘N
Approve pending agent runs
Navigate
Go to dashboard⌘1
Trigger · Sheet from Trigger child · Popover anchored to trigger · Command via ⌘K globally Figma: sheet/* · popover/* · command/*
05

Data display

Containers and tables for structured content. Dense by default — this is an enterprise tool.
Table
table/*
Sortable, dense, monospace IDs. Default row height 40px; compact 32px for high-density screens.
Agent Status Last run Tool calls Success rate
acme-onboarding
agent_01HVE2Q
 Live 2m ago 234 98.7%
invoice-reconciler
agent_01HVE3B
 Throttled 12m ago 1,204 94.1%
supplier-research
agent_01HVE4M
 Draft — 0 —
crm-syncer
agent_01HVE7Z
 Failed 1h ago 12 42.0%
Property · columns (definition) · density ∈ {comfortable, compact} Figma: table/{row-state} · table-cell/{type}
Card, Avatar, Accordion, Code block
card · avatar · accordion · codeblock
Smaller building blocks for composed layouts.
acme-onboarding
12 instances · 2m ago
Live
Onboards new Acme Corp employees through HR systems, sends welcome packets, and provisions accounts.
AVATARS
JF FC MR SP
What is an agent run?
A run is one full execution of an agent from prompt to completion. Each run has its own tool-call budget and audit log.
How do tool calls get billed?
CODE BLOCK
// Run an agent from the SDK const run = await ask.agents.run({ agent: "acme-onboarding", input: { employee: "jane@acme.io" }, });
Avatar · size, tone, fallback · Accordion · collapsible, multi-open boolean Figma: card/* · avatar/{size} · accordion · codeblock
06

Forms

Composed input patterns. Field is the canonical wrapper for any control with a label, help, or error.
Field & form layout
field/* · form
Vertical stack with 6–8px between label, input, and help/error. Required fields show an asterisk in ASK Red.
Agent name * Lowercase, hyphens only. Used as the agent's stable identifier in logs and API calls.
Model
Slack webhook URL Missing colon after https
Description 320 / 500 characters
Property · label, help, error, required · Form spacing: 16px between fields, 24px before actions Figma: field/{kind} · form/{layout}
07

Agentic AI primitives

Domain-specific patterns. The components that make ASK feel like ASK — tool calls, agent status, citations, streaming text. See § 09 for the full Verified Citation pattern.
Chat messages
agentic/message
Three message types: user (filled bubble), agent (no bubble, with avatar), system (italic, small). Agent messages can contain inline citations and tool-call cards.
Find every supplier invoice from Q1 that hasn't been reconciled with our ERP, then draft a follow-up email to each vendor.
FC
A
acme-financethinking
I'll start by querying the ERP for unreconciled Q1 invoices, then cross-reference against our supplier database.
erp.query complete · 412ms
sql: "SELECT * FROM invoices WHERE q='Q1' AND reconciled=false" rows: 47
Found 47 unreconciled invoices totaling €1.2M across 18 suppliers 1. Let me prepare the follow-ups now…
Agent paused for human approval · approve to continue
Property · role ∈ {user, agent, system} · supports inline Citation and ToolCall Figma: agentic/message/{role}
Tool-call card
agentic/tool-call
A single tool invocation: name, arguments, duration, result. Three states: pending, running (animated), complete, error.
web_search complete · 1.4s
query: "Acme Corp supplier list 2025" results: 8 · top: "acme-suppliers.csv (sharepoint)"
read_doc running
path: "/sharepoint/finance/Q1-invoices.xlsx"
send_email error · 401
SMTP relay rejected: missing OAuth scope "mail.send"
Property · tool, args, status ∈ {pending, running, complete, error} · duration Figma: agentic/tool-call/{status}
Agent status, Citations, Streaming
agentic/status · agentic/citation · streaming
The signals that communicate state without taking space.
STATUS
Idle Running · step 4 / 12 Failed at send_email
CITATIONS
The Q1 reconciliation report flagged 47 unmatched invoices 1, primarily from 3 suppliers 23.
STREAMING TEXT
Drafting your follow-up email to Vendor A
Citations link to source · Status LED uses CSS keyframes (pulse / blink) Figma: agentic/status/{state} · agentic/citation
08

Environments

ASK runs three execution modes. Each has a distinct cognitive contract with the user — and the chrome must visibly enforce that contract. The environment badge is non-negotiable.
CHAT
General Chat
Driver · Autonomous agent interaction, daily versatility.
Layout · Wide centered conversational. Rapid text input, dynamic results.
State · Ephemeral (no persistence by default).
Writes · Disabled. Read-and-suggest only.
NOTEBOOK
Notebook
Driver · Deep exploration of a Knowledge Pod.
Layout · Split-screen. Prompts left, pinned sources right.
State · Persistent. Context and files saved.
Writes · Read-only against documents. Drafting and synthesis.
VERTICAL
Vertical App
Driver · Logic-driven, transactional workflow execution.
Layout · Structured forms, wizards, progress steppers.
State · Transactional. Linked to external systems.
Writes · Enabled with mandatory HITL confirmation.
Chrome — General Chat
env/chat
Minimal chrome. Centered conversational column. The mode badge in the top bar identifies the environment, nothing else.
CHAT
New conversation
Ephemeral session FC
A
ASK
What would you like to explore? I have read access to your indexed documents but cannot write to external systems from this mode.
Chrome rule · Outline-style badge marks the mode without taking visual weight from content Figma: env/chat/chrome
Chrome — Notebook
env/notebook
High-visibility Knowledge Pod badge. Split-screen layout. The Pod boundary is always visible — users can never forget what they're scoped to.
NOTEBOOK
Knowledge Pod · Legal Department · Senior Only
Persistent · 12 files indexed FC
Summarize the indemnity clauses across all NDAs signed in Q1.
FC
A
Across 8 NDAs signed in Q1, three indemnity patterns emerge12. The most stringent terms appear in the Acme Corp agreement3.
PINNED SOURCES
NDA_Acme_2026.pdf
p.12
NDA_Globex_2026.pdf
p.4
NDA_Initech_Q1.pdf
p.7
Chrome rule · Knowledge Pod badge persists across scroll. Right pane width 320px minimum, collapsible. Figma: env/notebook/chrome · env/notebook/pod-badge
Chrome — Vertical App
env/vertical
Process-specific chrome. App badge identifies the workflow. Stepper replaces freeform input. Write actions surface only through HITL confirmation (Pattern B).
VERTICAL
Contract Reviewer
Transactional · Step 2 / 4 FC
✓
Upload contract
2
Review clauses
3
Approve actions
4
Log to ERP
Step 2 · Review extracted clauses
3 indemnity clauses, 1 limitation of liability, 1 termination clause
Read-only
… clauses table goes here, with checkboxes to mark for ERP logging …
Chrome rule · App identity badge is ink-on-white. Stepper is mandatory for any multi-step write. Free-form input is forbidden in this mode. Figma: env/vertical/chrome · env/vertical/stepper · env/vertical/app-badge
09

Compliance patterns

Four mandatory patterns that enforce structural safety through visual contracts. These are not stylistic choices — they are load-bearing parts of the architecture. Designs that omit them must be rejected at review.
Pattern A · Verified Citation Block
compliance/citation
Combats the "Oracle Illusion." Every factual assertion the system makes must carry an inline, interactive citation. Clicking it opens a sidebar pane showing the exact semantic text segment and source file origin. No single block of unverified prose is allowed.
ASK RESPONSE
The Q1 reconciliation report flagged 47 unmatched invoices across 18 suppliers 1. The largest exposure sits with Acme Corp at €312k, primarily owed to a misconfigured PO numbering scheme 2. A second cluster involves three suppliers using legacy IBAN formats not yet migrated to SEPA v2 3.

According to the company's published reconciliation SLA, items overdue beyond 30 days must trigger an escalation to the CFO 4.
▸ Behavior  Clicking 1 highlights the source block in the right pane. Hovering shows a snippet tooltip with the first 120 chars.
1 Source · Citation 1
Q1_Reconciliation_Report.pdf
Finance / 2026 · page 12
"As of 31 March 2026, 47 supplier invoices remain unmatched against ERP records, distributed across 18 distinct suppliers. The largest cluster is concentrated in the Acme Corp account at €312,401.50…"
Required for · every factual claim in agent output. Property · citationId, source, page, quote. Figma: compliance/citation/inline · compliance/citation/source-pane
Pattern B · Human-in-the-Loop Validation
compliance/hitl
Single-click submit is forbidden for any write to an external system. Use a deliberate double-action: slide-to-approve, or a multi-checkbox confirmation panel that surfaces the exact payload. Accidental execution must be structurally impossible.
Slide to approve
Compact form — for individual writes
Action: Create Jira ticket PROJ-1247
Verify target details below. Confirming this action will write data permanently to jira.company.io.
Slide to approve →
Track length ≥ 240px · arc swipe of 60° on touch
Multi-checkbox confirmation
For high-stakes writes with structured payload
Confirming this action will write data permanently to ERP · Vendors. Acknowledge each line:
Target system · erp_prod_vendor Operation · INSERT · 18 records Payload reviewed · preview JSON ↗ I am authorized to perform this write
Required microcopy: "Verify target details below. Confirming this action will write data permanently to [Target System]." — do not paraphrase. The specific target name must be substituted in.
Required for · any tool call with side effects in external systems (Jira, ERP, CRM, email, etc.) Figma: compliance/hitl/slide-approve · compliance/hitl/multi-checkbox
Pattern C · Active Guardrail Interventions
compliance/guardrail
When middleware filters scrub PII or block out-of-scope requests, the system stays operational — but it must transparently signal what happened. Calm, non-disruptive, never alarming. Two tones: active (filter ran, work continues) and blocked (request rejected).
GUARDRAIL ACTIVE PII detected · automatically anonymized
3 customer names and 1 IP address were replaced with redaction tokens before being sent to the model. Original values remain in your tenant.
GUARDRAIL BLOCK Out of scope
This App is restricted to Contract Review — it cannot process payroll-related questions. Switch to the Payroll Assistant instead.
Switch app
TOAST FORM
Guardrail active
2 PII fields anonymized before processing
Tone rule: Guardrails are infrastructure, not failures. Never use Danger red for a successful filter run. Active = Info blue. Block = Warning amber. Only true errors (filter failed to run) escalate to Danger.
Required for · every middleware intervention. Always tell the user what was scrubbed or blocked, and why. Figma: compliance/guardrail/active · compliance/guardrail/block · compliance/guardrail/toast
Pattern D · Implicit RBAC Filtering
compliance/rbac
Zero-trust UI. Users must never see options they cannot execute. Buttons, actions, or input paths beyond the user's RBAC scope — or the App's manifesto — are entirely omitted. Disabled and grayed-out states are forbidden for unauthorized actions, because they leak the existence of unprivileged paths.
DO Omit unauthorized items
Workflow actions
Run
Duplicate
View history
Viewer role.
The user has no write or delete permission.
Those actions are not in the menu — the user has no way to know they exist.
DON'T Gray out unauthorized items
Workflow actions
Run
Edit (insufficient role)
Delete (insufficient role)
Leaks information.
The user learns that Edit and Delete exist — and that someone else can do them.
Creates UX friction and a footprint for privilege-escalation phishing.
The rule: Permissions are the strict intersection of the user's RBAC scope and the App's configuration manifesto. If the answer is "no," the option does not exist in the DOM. Empty states are fine. Disabled-for-permission is never fine.
Required for · every action menu, button group, navigation list. Property · visible driven by RBAC selector at render time. Figma: compliance/rbac/do · compliance/rbac/dont
10

App shell

Page-level scaffolds. Compositions of nav + page header + content area.
Page header
shell/page-header
Title, optional metadata row, and primary actions. Sits between top nav and content.
Workspace/Agents

acme-onboarding

Live · agent_01HVE2Q · Owned by Federico · 234 runs this month
… page content area …
Property · title, breadcrumbs, actions, metadata Figma: shell/page-header
→

Next steps

How to take this from documentation into living artifacts across Figma and code.
  1. Create the ASK · Design System Figma project with three files: Foundations, Components, Patterns. FIGMA-LIBRARY.md has the full structure.
  2. Import design-tokens/figma/tokens-studio.json into the Foundations file via the Tokens Studio plugin. IMPORT.md walks through it.
  3. Build the Components file using this document as the visual spec. Every comp-foot shows the Figma component path and code import.
  4. Wire shadcn/globals.css and shadcn/tailwind.preset.ts into apps/web. Run npx shadcn add button input dialog — the components will pick up Ask tokens automatically.
  5. Add a BrandSheet.stories.tsx in Storybook that renders the foundations — Chromatic will catch any drift in tokens as visual regression.
  6. Set up Tokens Studio's GitHub sync once the library stabilizes — designers can then PR token changes directly from Figma.
One vocabulary. Three surfaces.
tokens.json → Figma · shadcn · Storybook · Chromatic
ASK Design System · v1.0 · 2026-05-21